Skip to main content

Getting Started

tip

Stoker is in alpha mode. We're currently offering free support (subject to availability). Get in touch at info@getoutpost.com and we'll add you to our private Slack support channel. You can also submit issues on GitHub.

The Basics​

These steps are detailed below.

  1. Install Stoker and the required tools
  2. Fill out a simple .env file that describes your back-end infrastructure (for example, hosting regions).
  3. Fill out your global config file (project-wide config)
  4. Create a schema file for each "collection" required in your app. Defaults are provided for Users, Settings, Inbox and Outbox.
  5. Set up your development environment
  6. Add tenants to your app using stoker add-tenant (one tenant for each organization that will use your app)
  7. Hit stoker deploy to deploy changes

Installation​

Prerequisites:

  • Google Account (must have a Google Cloud billing account)
  • Node JS 22+
  • Firebase CLI:
    • npm i -g firebase-tools
    • firebase login
  • Google Cloud CLI:
    • Prerequisites:
    • Installation:
      • Install
      • gcloud init
      • gcloud auth application-default login
  • Genkit CLI:
    • npm i -g genkit-cli

Stoker:

  • npm i -g @stoker-platform/cli
  • Create a new directory i.e. "my-app" and cd into it
  • stoker init && git init && npm i && npm --prefix functions i

You might also want to update your package name in package.json.

info

You don't need to sign up to use Stoker at this stage, but you may need to in future.

Back End Setup​

The back end config for your app is found at env/.env in your project directory.

You can use the defaults to get started, but you MUST provide:

  • General:

    • ADMIN_EMAIL: The email address to be used for system notifications
    • ADMIN_SMS: The phone number to be used for system notifications
    • GCP_BILLING_ACCOUNT: Google Cloud Billing Account ID

  • Mail (used to send email out of the system):

    • MAIL_REGION: A Google Cloud region supported by Eventarc
    • MAIL_SENDER: i.e. Stoker Platform <username@gmail.com>
    • MAIL_SMTP_CONNECTION_URI: i.e. smtps://username@gmail.com@smtp.gmail.com:465
    • MAIL_SMTP_PASSWORD: i.e. a Gmail app password

Recommended but not required:

  • Google Analytics Account ID
  • Sentry DSN
  • Algolia credentials. Used for full text search in collections with large volumes of data. For collections with small amounts of data, client side full text search is used by default.
  • Twilio credentials (used to send SMS out of the system):
    • TWILIO_ACCOUNT_SID
    • TWILIO_AUTH_TOKEN
    • TWILIO_PHONE_NUMBER

For more information, see Env Files - Back End Setup.

Icons​

  • You can use the default icons to get started.
  • Replace logo-small.png and logo-large.png in the icons directory with your own icons (keep the same file names).
  • Recommended sizes are 192 x 192 (logo-small) and 3000 x 3000 (logo-large).

Global Config File​

Your app's global config file is found at src/main.ts.

We recommend using the defaults to get started, but you MUST provide:

  • roles: This is the big one. Name the access roles that will be used in your app. Each role will have its own permissions.
  • appName: The name of your app. Shorter is better, as this will be used for page titles etc.
  • timezone: Your app will be based in this timezone. Must be a valid IANA timezone.

For more information, see Global Config File.

Collection Files​

Collection files are found at src/collections

The default collections are enough to get started.

warning

If you are not using the default roles "Admin" and "User", you will need to:

  • Go into each default collection file
  • Change all references to "Admin" and "User" to the roles you provided.

The most important concepts to know are:

For more information, see Collection Config Files.

Development Environment​

  1. Add a development tenant using stoker add-tenant -n <TENANT_NAME> --development. You'll be prompted to add an organization name and the first user for the tenant.
  2. Navigate to the tenant by running export GCP_PROJECT=<TENANT_NAME> && stoker set-tenant
  3. Run stoker emulator-data
  4. npm run start
  5. Navigate to localhost:4001 and add the password for your test user in the Authentication section (each time you run npm run start).
  6. Navigate to localhost:5173 to see your app. All data will be reset each time you run npm run start.
  7. If you are using App Check, set up your App Check debug token (steps 2 & 3 here)

When you make changes to your app schema, you may need to close your terminal session and re-run npm run start.

You may need to clear the required ports on your system before re-running npm run start.

Production Tenants​

You can add production tenants to your app using stoker add-tenant -n <TENANT_NAME>

Each tenant gets its own Google Cloud / Firebase project, ensuring isolation.

You can view the app for a tenant at https://<TENANT_NAME>.web.app

Add a custom domain using stoker custom-domain.

We recommend setting up notifications in Error Reporting for each production tenant in the Google Cloud console. That way you'll get emailed whenever your back end services throw an error.

Deployment​

To deploy your latest changes to a tenant:

  • Navigate to the tenant by running export GCP_PROJECT=<TENANT_NAME> && stoker set-tenant
  • stoker deploy

info

Important Privacy Notice​

All of your app data is stored in your own Google Cloud projects. We do NOT have access to your Google Cloud projects or your app data.

When you deploy with stoker deploy or add a tenant with stoker add-tenant, the following occurs:

  • Your Stoker schema (JSON) is sent to our server.
  • Our server returns Firestore Indexes, Firestore Security Rules and Firebase Storage Security Rules for your project.
  • We do not store, log, or retain your schema, generated rules, or index definitions after the request is completed. They are processed in-memory solely for the purpose of generating the required Firebase configuration files.
  • No AI is used in the generation of your rules / indexes.

No analytics or tracking data are collected from the Stoker CLI.

This is a summary provided for convenience. For legal definitions, please review our full Privacy Policy.